ahrf is an awk
script designed to interpret a simple and straightforward
ASCII file format. I wrote it to share my personal documentation, which is
written in plain text files. They can be exported to HTML.
The main goal was... readability.
- One requirement:
awk
- Supporting many
awk
variants (nawk
,mawk
,gawk
or OpenBSDawk
) (cf "Compatibility") - Simple syntax
- Easy to use / remember / extend
- Designed to work with wswsh
- File format can be parsed by almost everything:
sed
,sh
,python
orC
: My important page title :
<h1>My important page title</h1>
:: This is the category title ::
<h2>This is the category title</h2>
and so on...
::: ::: for <h3></h3>
:::: :::: for <h4></h4>
::::: ::::: for <h5></h5>
:::::: :::::: for <h6></h6>
It's possible to define a heading, without the second :::
field (but it
would be less readable):
::: My title without the second field
You just need to put your paragraph inside the file. Nothing else is required:
DTLS memory leak from zero-length fragments (CVE-2014-3507)
OpenSSL DTLS anonymous EC(DH) denial of service (CVE-2014-3510)
Race condition in ssl_parse_serverhello_tlsext (CVE-2014-3509)
OpenSSL TLS protocol downgrade attack (CVE-2014-3511)
<p>DTLS memory leak from zero-length fragments (CVE-2014-3507)
OpenSSL DTLS anonymous EC(DH) denial of service (CVE-2014-3510)
Race condition in ssl_parse_serverhello_tlsext (CVE-2014-3509)
OpenSSL TLS protocol downgrade attack (CVE-2014-3511)</p>
Line breaks are supported. You just need to add one or more "ghost" space(s) at the end of the line:
This could be exploited in a Denial Of Service attack.▉
This issue affects OpenSSL 1.0.1 server implementations for both SSL/TLS
and DTLS regardless of whether SRTP is used or configured.▉
Reported by LibreSSL project.
<p>This could be exploited in a Denial Of Service attack.<br>
This issue affects OpenSSL 1.0.1 server implementations for both SSL/TLS
and DTLS regardless of whether SRTP is used or configured.<br>
Reported by LibreSSL project.</p>
Paragraphs can start by:
0-9
: From0
to9
A-Z
: All letters uppercasea-z
: All letters lowercase_
,(
,"
,`
Code blocks must start by 4 =
at least.
====
Filesystem Size Used Avail Use% Mounted on
/dev/sda5 12G 2.5G 8.6G 23% /
dev 3.9G 0 3.9G 0% /dev
run 4.0G 592K 3.9G 1% /run
tmpfs 4.0G 0 4.0G 0% /dev/shm
====
<pre><code>Filesystem Size Used Avail Use% Mounted on
/dev/sda5 12G 2.5G 8.6G 23% /
dev 3.9G 0 3.9G 0% /dev
run 4.0G 592K 3.9G 1% /run
tmpfs 4.0G 0 4.0G 0% /dev/shm</code></pre>
=======
ls /usr/local/etc/rc.d/
=======
<pre><code>ls /usr/local/etc/rc.d/</code></pre>
You need to add one or more space(s) after *
. If you omit that, the
item(s) will be ignored.
* Eat cooked meat
* Buy french bread
* Peel potatoes
* Drink beers
<ul>
<li>Eat cooked meat</li>
<li>Buy french bread</li>
<li>Peel potatoes</li>
<li>Drink beers</li>
</ul>
* Homemade sausage
* Apple pie
*Be fast
* Don't be in a hurry
<ul>
<li>Homemade sausage</li>
<li>Apple pie</li>
<li>Don't be in a hurry</li>
</ul>
The "list" has to be started by [0]
or [1]
. If not, it won't be matched.
[0] https://github.com/
[1] http://netbsd.org/
[2] http://ywstd.fr/
[666] http://www.libressl.org/
<ul>
<li>[0] <a href="https://github.com/">https://github.com/</a></li>
<li>[1] <a href="http://netbsd.org/">http://netbsd.org/</a></li>
<li>[2] <a href="http://ywstd.fr/">http://ywstd.fr/</a></li>
<li>[666] <a href="http://www.libressl.org/">http://www.libressl.org/</a></li>
</ul>
There is no specific regex for the comments. If the line doesn't "satisfy"
the above specs, it'll be just ignored. However, starting comments by #
is perfect. The readers will be able to see them, in less than 0,25 ms
(yes, many configuration files use #
).
To avoid invalid HTML code, the symbols >
, <
and &
are automatically
replaced by their HTML counterparts.
The valid ouput can be found within the files *.outvalid
inside the
directory test
.
It's a VERY good idea to check those results to understand how ahrf
behaves.
To prevent introducing regressions when regexes are reworked, improved or
expanded, a sh
script was written to check and compare ahrf
output. It's
called verify_regr.sh
. It can be launched via your_shell verify_regr
or
make check
for the lazy men. make clean
deletes the invalid files from
the last checking. I strongly advise you to run it for every changes!
The following awk
variants were validated using the regressions test (no
issues triggered).
The versions are printed here:
-
nawk
-Dec 20, 2012
-
mawk
(some problems before20141027
) -mawk 1.3.4 20141027
&mawk-1.3.4-20141206
-
OpenBSD
nawk
-awk version 20110810
-
fatbase awk (Another portable OpenBSD tools from 2f30 folks)
-
NetBSD 7.0_BETA
awk
-awk version 20121220
(thanks to @justincormack) -
gawk
-GNU Awk 4.1.1
-
OSX
awk
(probably anawk
), but I don't have the exact version number. However, I do not plan to test this "variant" for every new changes.
I used nawk
when I wrote this script. It can be found
here.
make all
(or simply make
) will launch the tests for every variants
specified in AWKV
.
This script wasn't created to mimic or replace markdown
syntax. Therefore,
I do not ask or force anybody to adopt it. I want to write my own documentation
or cheatsheets using an easy "system".
markdown
can be very frustrating when you use a lot of preformatted text
or lists and the result is sometimes totally broken and wrong. For example,
when I wrote that README.md
, I encountered many times malformed output or
bad matches.
I'm not even talking about the dozens of differents variants /
implementations... And do not tell me I don't know what I'm talking about
because I "played" thousands of times with markdown
.
Maybe. I'm not enough confident to write a bugless script. Report them! If you notice something wrong, try to provide me an ascii file with your lines. I'll be able to work on/debug it.
Code created by Ypnose, under BSD (3-Clause) License
Thanks to Alexander for serving me as a guinea pig.